﻿<h1>1. HTML写文档约定</h1>
<p>
内容授权：<a href="http://www.opensource.org/licenses/bsd-license.php" target=_blank>BSD 许可证</a><br/>
完成日期：2009-08-25</p>
<p>
作者：史荣久(trydofor)<br/>
邮箱：<a href="mailto:trydofor@gmail.com" target=_blank>trydofor@gmail.com</a><br/>
网址：<a href="http://www.trydofor.com/" target=_blank>www.trydofor.com</a></p>

<h2>1.1. 为何HTML</h2>
<p>
选择了HTML格式的根本原因是为了方便读者，便于阅读和分享。
同时考虑到作者，我们对HTML标签进行了分类整理和用法约定后发现其
可以在学习曲线接近WIKI，功能上效仿DOCBOOK，操作上不依赖第三方工具。</p>

<h2>1.2. 文档结构</h2>
<p>
文章 = 1*小节<br/>
小节 = 标题 1*段落<br/>
标题 = "&lt;H#&gt;" 序号 0X20 普通文本 "&lt;/H#&gt;" ; #=[1-6]<br/>
序号 = 1*(数字 ".") ;数字=[0-9]<br/>
段落 = 段落标签 *(格式文本 / 普通文本)<br/>
段落标签 = ;详见，<a href="#1.3.2.">1.3.2. 段落标签</a><br/>
内联标签 = ;详见，<a href="#1.3.3.">1.3.3. 内联标签</a><br/>
格式文本 = 内联标签 普通文本<br/>
普通文本 = ;没有HTML标签的UNICODE字符<br/></p>

<h2>1.3. 标签分类</h2>
<p>
对文档中经常使用的ＨＴＭＬ标签及属性分类和说明，以统一文档结构和方便描述。</p>

<h3>1.3.1. 标题标签</h3>
<p>
用来定义小节标题，以H#表示，具体包括，H1/H2/H3/H4/H5/H6。<br/>
其中的#等于标题序号中"."的个数，即标题的层次。<br/>
比如，"1.2.3."对应H3，而"1.2."对应H2.<br/></p>
<p>
建议采用以下格式：</p>
<p>
&lt;h3 id="1.3.2." &gt;1.3.2. 段落标签&lt;/h3&gt;</p>

<h3 id="1.3.2.">1.3.2. 段落标签</h3>
<p>
段落标签是指可以产生空行或者单独成块的标签。
各小节描述了在源码中建议使用的格式和属性，
通常不建议在段落标签内使用段落标签。</p>

<h4>1.3.2.1. &lt;blockquote&gt; &lt;/blockquote&gt;</h4>
<p>
引述一段文字，不建议在其内使用其他段落标签（BR除外）。</p>
<p>
建议采用以下格式：</p>
<p>
&lt;blockquote cite="URL"&gt;<br/>
引述块，不建议在其内使用其他段落标签（BR除外）。&lt;/blockquote&gt;</p>
<p>
效果如下：</p>
<blockquote cite="http://www.trydofor.com">
引述块，不建议在其内使用其他段落标签（BR除外）。</blockquote>

<h4>1.3.2.2. &lt;br/&gt;</h4>
<p>
产生一个换行。</p>
<p>
建议采用以下格式：</p>
<p>
需要换行显示的文字结尾&lt;br/&gt;</p>

<h4>1.3.2.3. &lt;dl&gt;&lt;dt&gt;&lt;/dt&gt;&lt;dd&gt;&lt;/dd&gt;&lt;/dl&gt;</h4>
<p>
对话的或定义的列表，其中，<br/>
dt，表示定义或发言者。<br/>
dd，表示定义或对话。</p>
<p>
建议采用以下格式：</p>
<p>
&lt;dl&gt;<br/>
&lt;dt&gt;定义或发言者1&lt;/dt&gt;&lt;dd&gt;解释或对话1&lt;/dd&gt;<br/>
&lt;dt&gt;定义或发言者2&lt;/dt&gt;&lt;dd&gt;解释或对话2&lt;/dd&gt;&lt;/dl&gt;</p>
<p>
效果如下：</p>
<dl>
<dt>定义或发言者1</dt><dd>解释或对话1</dd>
<dt>定义或发言者2</dt><dd>解释或对话2</dd></dl>

<h4>1.3.2.4. &lt;ol&gt;&lt;li&gt;&lt;/li&gt;&lt;/ol&gt;</h4>
<p>
有序列表或步骤。<br/>
li，表示一个条目。</p>
<p>
建议采用以下格式（不建议使用type属性）：</p>
<p>
&lt;ol type="A|a|I|i|1" start="X"&gt;<br/>
&lt;li&gt;条目1&lt;/li&gt;<br/>
&lt;li&gt;条目2&lt;/li&gt;&lt;/ol&gt;</p>
<p>
效果如下：</p>
<ol>
<li>条目1</li>
<li>条目2</li></ol>

<h4>1.3.2.5. &lt;ul&gt;&lt;li&gt;&lt;/li&gt;&lt;/ul&gt;</h4>
<p>
一个无序列表。<br/>
li，表示一个条目。</p>
<p>
建议采用以下格式（不建议使用type属性）：</p>
<p>
&lt;ul type="disc|square|circle"&gt;<br/>
&lt;li&gt;条目1&lt;/li&gt;<br/>
&lt;li&gt;条目2&lt;/li&gt;&lt;/ul&gt;</p>
<p>
效果如下：</p>
<ul>
<li>条目1</li>
<li>条目2</li></ul>

<h4>1.3.2.6. &lt;p&gt; &lt;/p&gt;</h4>
<p>
声明一个段落。不建议在其内使用其他段落标签（BR除外）。</p>
<p>
建议采用以下格式：</p>
<p>
&lt;p&gt;<br/>
段落内的文字，不建议使用其他段落标记（BR除外）。&lt;/p&gt;</p>
<p>
效果如下：</p>
<p>
段落内的文字，不建议使用其他段落标记（BR除外）。</p>

<h4>1.3.2.7. &lt;pre&gt; &lt;/pre&gt;</h4>
<p>
预格式文本，其内保留空格，换行等字符。不建议其内使用其他段落标签。</p>
<p>
建议采用以下格式：</p>
<p>
&lt;pre&gt;<br/>
段落内的文字，不建议使用其他段落标记（BR除外）。&lt;/pre&gt;</p>
<p>
效果如下：</p>
<pre>
预格式化文本，一般使用等宽字体，并保留空格和换行效果。</pre>

<h4>1.3.2.8. &lt;table&gt;&lt;tr&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;</h4>
<p>
绘制一个表格。其中，<br/>
tr表示一行。<br/>
td表示一列。<br/>
th表示一列（表头）。</p>
<p>
建议采用以下格式（不建议使用colspan,rowspan属性）：</p>
<p>
&lt;table&gt;<br/>
&lt;tr&gt;<br/>
&lt;th colspan=X rowspan=X&gt;Header 11&lt;/th&gt;<br/>
&lt;th&gt;Header 12&lt;/th&gt;&lt;/tr&gt;<br/>
&lt;tr&gt;<br/>
&lt;td colspan=X rowspan=X&gt;Cell 21A&lt;/td&gt;<br/>
&lt;td&gt;Cell 22B&lt;/td&gt;&lt;/tr&gt;<br/>
&lt;/table&gt;<br/></p>
<p>
效果如下：</p>
<table border="1">
<tr>
<th colspan="2">一一（一二）</th>
<th>一三</th></tr>
<tr>
<td>二一</td>
<td>二二</td>
<td rowspan="2">二三（三三）</td></tr>
<tr>
<td>三一</td>
<td>三二</td></tr>
</table>

<h3 id="1.3.3.">1.3.3. 内联标签</h3>
<p>
指不会产生换行，在行内起到修饰作用的标签。</p>

<h4>1.3.3.1. a</h4>
<p>
超链接。</p>
<p>
建议采用以下格式（不建议使用type属性）：</p>
<ul>
<li>连接到外部：&lt;a href="URL" target="_blank" &gt;显示名&lt;/a&gt;</li>
<li>连接到锚点：&lt;a href="#ID" &gt;显示名&lt;/a&gt;</li></ul>

<p>
<b>注意：</b>定义锚点，请使用各种标签的ID属性，不建议使用a的name属性。</p>

<h4>1.3.3.2. b/del/i/sub/sup</h4>
<p>
被修饰文本的效果分别是，加粗/删除线/倾斜/上标/下标。</p>
<p>
&lt;b&gt;加粗&lt;/b&gt;
&lt;del&gt;删除线&lt;/del&gt;
&lt;i&gt;倾斜&lt;/i&gt;
&lt;sub&gt;上标&lt;/sub&gt;
&lt;sup&gt;下标&lt;/sup&gt;</p>
<p>
效果如下：<b>加粗</b> <del>删除线</del> <i>倾斜</i> <sub>上标</sub> <sup>下标</sup></p>


<h4>1.3.3.3. img</h4>
<p>
插入图片。</p>
<p>
&lt;img src="$URL" alt="Text" /&gt;</p>
<p>
效果如下：<img src="../logo/logo-143x59.png" alt="logo 143x59" /></p>

<h2>1.4. 字符转义</h2>
<p>
常用的HTML字符转义。</p>
<table border="1">
<tr>
<th>显示</th>
<th>说明</th>
<th>名称形式</th>
<th>编码形式</th></tr>
<tr>
<td>&lt;</td>
<td>小于</td>
<td>&amp;lt;</td>
<td>&amp;#60;</td></tr>
<tr>
<td>&gt;</td>
<td>大于</td>
<td>&amp;gt;</td>
<td>&amp;#62;</td></tr>
<tr>
<td>&amp;</td>
<td>&amp;符号</td>
<td>&amp;amp;</td>
<td>&amp;#38;</td></tr>
<tr>
<td>&quot;</td>
<td>双引号</td>
<td>&amp;quot;</td>
<td>&amp;#34;</td></tr>
<tr>
<td>&nbsp;</td>
<td>不断开空格(non-breaking space)</td>
<td>&amp;nbsp;</td>
<td>&amp;#160;</td></tr>
</table>

<h2>1.5. 通用规则</h2>
<ul>
<li>不建议限定文档格式。比如，样式表（CSS）或属性。</li>
<li>不建议使用脚本。比如，Javascript。</li>
<li>各标签均有ID属性，ID可作为锚点。</li></ul>

<h2>1.6. 参考资料</h2>
<ul>
<li><a href="http://www.w3schools.com/tags/html5.asp" target="_blank">HTML 5 reference at w3schools</a></li>
<li><a href="http://docbook.sourceforge.net/" target="_blank">docbook project at sourceforge</a></li></ul>
